wolfSupplicant: clean-room WPA/WPA2/WPA3 supplicant (PSK 4-way, EAP-TLS, PEAP/MSCHAPv2, SAE with H2E) by dgarske · Pull Request #123 · wolfSSL/wolfip

dgarske · 2026-05-20T17:58:11Z

wolfSupplicant: clean-room WPA2 / WPA2-Enterprise / WPA3 supplicant

Adds an in-tree Wi-Fi supplicant (src/supplicant/) built directly on wolfSSL/wolfCrypt: WPA2-Personal (PSK), WPA2-Enterprise (EAP-TLS, optional PEAP/MSCHAPv2), and WPA3-Personal (SAE). Transport-agnostic, caller-allocated context, no dynamic allocation on the bare-metal path. ~5,000 lines of C (~6,500 with headers), each method selectable at build time.

Commits

Core supplicant + interop harness - state machine, 4-way handshake, SAE dragonfly (sae_crypto.c), EAP-TLS engine (wolfSSL native + custom IO), AES-CMAC/Key-Wrap, RSN IE handling, and the host unit + hostapd test suite.
SoftMAC nl80211 STA glue + wolfsta + hwsim interop - tools/hostapd/nl80211_sta.c drives a Linux mac80211 station (AUTHENTICATE+SAE_DATA / ASSOCIATE / NEW_KEY / control-port) and wires it to the supplicant ops; tools/wolfsta/ is a wolfIP+supplicant host app (join -> DHCP -> ping/UDP echo).
STM32H563 wired 802.1X EAP-TLS demo - the supplicant authenticating on real hardware.
Raspberry Pi Pico 2 W (RP2350 + CYW43439) port - bare-metal scaffolding for the FullMAC PSK/SAE path.

What's validated

Against real hostapd over mac80211_hwsim (SoftMAC; same code path a TP-Link USB card uses), all reaching AUTHENTICATED:

Path	Status
WPA3-SAE P-256/P-384/P-521, Hunt-and-Peck + H2E (all 6)	green
WPA2-Enterprise EAP-TLS over the radio	green
WPA3-SAE PMKSA fast reconnect (no dragonfly on rejoin)	green
WPA3-SAE wrong-password rejected (negative)	green
wolfsta join + DHCP + ping + UDP echo (SAE and PSK)	green

Plus: STM32H563 authenticates over wired 802.1X EAP-TLS on hardware; host unit tests cover the 4-way, SAE crypto (incl. RFC 9380 J.1.1 P-256 KAT), EAP-TLS, and MSCHAPv2 vectors.

Notable correctness work

SAE 4-way uses Key Descriptor Version 0 (AES-128-CMAC) and the SHA-256 IEEE KDF for the PTK (vs Version 2 / HMAC-SHA1 for WPA2-PSK); RSN IE advertises AKM=SAE. AES-128-CMAC is implemented in-tree (RFC 4493 over AES-CBC), so no --enable-cmac dependency.
P-521 hunt-and-peck: the IEEE 802.11 KDF emits its 521 valid bits left-aligned, so the pwd-value is right-shifted by 8 - 521%8 = 7 bits before the < p test (matching hostapd's buf_shift_right) - the prior high-byte mask agreed with an in-process peer but not hostapd.
PMKSA fast reconnect on a SoftMAC userspace-SME radio uses open AUTHENTICATE + ASSOCIATE with the PMKID inline in the RSN IE (not the FullMAC SET_PMKSA path); hostapd matches the cached PMKSA and runs the 4-way directly.

Build flags

WOLFIP_ENABLE_EAP_TLS (1), WOLFIP_ENABLE_SAE (1, needs WOLFSSL_PUBLIC_MP), WOLFIP_ENABLE_SAE_H2E (1), WOLFIP_ENABLE_SAE_HNP (1), WOLFIP_ENABLE_PEAP_MSCHAPV2 (0, pulls in MD4/DES). Compile in only what you ship.

Testing

make supplicant-tests                              # host unit + crypto vectors
sudo make supplicant-hwsim-sae-softmac-test        # WPA3-SAE over a virtual radio
sudo make supplicant-hwsim-pmksa-test              # PMKSA fast reconnect
sudo make supplicant-hwsim-eap-softmac-test        # WPA2-Enterprise EAP-TLS

hwsim targets need root, mac80211_hwsim, hostapd, iw, and libnl-genl-3. See tools/hostapd/README.md for the full matrix and wolfSSL build flags.

Licensed GPLv3; commercial licensing available from wolfSSL.

Copilot

Pull request overview

Adds a clean-room WPA/WPA2/WPA3 supplicant (“wolfSupplicant”) to wolfIP and introduces Linux hostapd-based interop harnesses (wired + mac80211_hwsim) to validate EAP-TLS/PEAP, WPA2-PSK 4-way, and WPA3-SAE flows against a real authenticator.

Changes:

Introduces an optional Wi‑Fi control vtable (wolfIP_wifi_ops) and an EAPOL (0x888E) RX demux hook for supplicant integration.
Adds the supplicant implementation (src/supplicant/*) including EAP-TLS, PEAP/MSCHAPv2, RSN parsing, WPA(2) 4-way, and SAE (incl. H2E) plus test binaries.
Adds hostapd/mac80211_hwsim scripts + templates and an nl80211_connect helper, and wires new build/test targets into the Makefile.

Reviewed changes

Copilot reviewed 50 out of 50 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
wolfip.h	Adds Wi‑Fi ops vtable + public EAPOL handler registration API.
src/wolfip.c	Implements EAPOL handler registration and EAPOL ethertype demux in RX path.
src/test/unit/unit_tests_dns_dhcp.c	Adds unit coverage for EAPOL handler register/unregister behavior.
src/test/unit/unit.c	Registers the new unit test in the suite.
Makefile	Adds supplicant build outputs and hostapd/hwsim interop targets (+ nl80211 helper build).
src/supplicant/supplicant.c	Core supplicant state machine (PSK/EAP/SAE integration).
src/supplicant/supplicant.h	Supplicant public interface/types.
src/supplicant/eapol.c	802.1X/EAPOL framing helpers.
src/supplicant/eapol.h	EAPOL constants and APIs.
src/supplicant/eap.c	EAP packet parsing/building.
src/supplicant/eap.h	EAP structs/APIs and documentation for EAP parsing/building.
src/supplicant/eap_tls.c	EAP-TLS outer method implementation.
src/supplicant/eap_tls.h	EAP-TLS API/types.
src/supplicant/eap_tls_engine.c	TLS engine glue (wolfSSL IO/exporter integration) for EAP-TLS/PEAP.
src/supplicant/eap_tls_engine.h	TLS engine API/types.
src/supplicant/eap_peap.c	PEAP outer method implementation (when enabled).
src/supplicant/eap_peap.h	PEAP API/types.
src/supplicant/mschapv2.c	MSCHAPv2 inner method implementation (when enabled).
src/supplicant/mschapv2.h	MSCHAPv2 API/types.
src/supplicant/rsn_ie.c	RSN IE parse/build utilities (AKM/ciphers).
src/supplicant/rsn_ie.h	RSN IE API/types.
src/supplicant/wpa_crypto.c	WPA(2) key derivation/PRFs and related crypto helpers.
src/supplicant/wpa_crypto.h	WPA crypto API/types.
src/supplicant/sae_crypto.c	SAE (dragonfly) + H2E crypto/state helpers.
src/supplicant/sae_crypto.h	SAE crypto API/types.
src/supplicant/test_eap_certs.h	Test certificate material helpers for EAP-TLS/PEAP tests.
src/supplicant/test_eap_framing.c	Unit tests for EAP framing/parsing.
src/supplicant/test_eap_tls_engine.c	Unit tests for EAP-TLS engine behavior.
src/supplicant/test_mschapv2.c	Unit tests for MSCHAPv2 vectors.
src/supplicant/test_wpa_crypto.c	Unit tests for WPA crypto routines.
src/supplicant/test_supplicant_4way.c	In-process tests for 4-way handshake state machine.
src/supplicant/test_supplicant_eap_tls.c	In-process tests for EAP-TLS supplicant flow.
src/supplicant/test_sae_crypto.c	Unit tests/vectors for SAE crypto (incl. H2E).
src/supplicant/test_supplicant_sae.c	In-process tests for SAE handshake state machine.
src/supplicant/test_supplicant_hostapd.c	Wired hostapd interop test binary for EAP-TLS.
src/supplicant/test_supplicant_hostapd_psk.c	hostapd interop test binary for WPA2-PSK path.
src/supplicant/test_supplicant_hostapd_peap.c	hostapd interop test binary for PEAP/MSCHAPv2 path.
src/supplicant/test_supplicant_hostapd_sae.c	nl80211 external-auth hostapd interop test binary for SAE.
tools/hostapd/README.md	Documents hostapd-based interop harness setup/targets/flags.
tools/hostapd/run_hostapd_test.sh	Runner for wired hostapd interop (veth pair).
tools/hostapd/run_hwsim_psk_test.sh	Runner for mac80211_hwsim WPA2-PSK interop (nl80211 + hostapd).
tools/hostapd/run_hwsim_sae_test.sh	Runner for mac80211_hwsim SAE interop attempt (documents SoftMAC limitation).
tools/hostapd/hostapd.conf.template	hostapd wired-mode EAP server template for interop harness.
tools/hostapd/hostapd_psk.conf.template	hostapd PSK template for wired path (documented limitation).
tools/hostapd/hostapd_psk_hwsim.conf.template	hostapd nl80211 WPA2-PSK AP template for hwsim path.
tools/hostapd/hostapd_sae_hwsim.conf.template	hostapd nl80211 WPA3-SAE AP template for hwsim path.
tools/hostapd/eap_users	EAP users file for EAP-TLS interop.
tools/hostapd/eap_users_peap	EAP users file for PEAP/MSCHAPv2 interop.
tools/hostapd/nl80211_connect.c	Minimal libnl nl80211 client to associate STA with CONTROL_PORT for external EAPOL handling.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 90 out of 90 changed files in this pull request and generated 5 comments.

…PA3-SAE interop Adds the SoftMAC path that lets the wolfSupplicant's WPA3-SAE (and PSK / 802.1X) handshakes run over a real mac80211 radio - mac80211_hwsim for hardware-free CI, or a SoftMAC USB card (TP-Link ath9k_htc / rtl8xxxu / mt76). - tools/hostapd/nl80211_sta.{c,h}: reusable STA radio glue. SAE via NL80211_CMD_AUTHENTICATE (Commit/Confirm in NL80211_ATTR_SAE_DATA) + NL80211_CMD_ASSOCIATE; PSK/802.1X via NL80211_CMD_CONNECT; PTK/GTK install via NL80211_CMD_NEW_KEY; EAPOL over the AF_PACKET control port. - src/supplicant/test_supplicant_hwsim_sae_softmac.c + the run_hwsim_sae_softmac_test.sh / -h2e runners and Makefile targets (supplicant-hwsim-sae-softmac-test, -h2e-test). Validated to AUTHENTICATED against hostapd over mac80211_hwsim for both hunt-and-peck and RFC 9380 H2E (P-256). - tools/wolfsta/: wolfIP + wolfSupplicant host STA application that joins a network and obtains a DHCP lease over the encrypted link. Unlike the FullMAC external-auth path (test_supplicant_hostapd_sae.c), this is the surface mac80211_hwsim supports, so it validates with no hardware.

Copilot

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

dgarske self-assigned this May 20, 2026

dgarske force-pushed the supplicant branch from 8287b22 to a9d1959 Compare June 10, 2026 00:02

Copilot AI review requested due to automatic review settings June 10, 2026 00:07

dgarske force-pushed the supplicant branch from a9d1959 to 34dd36f Compare June 10, 2026 00:07

Copilot started reviewing on behalf of dgarske June 10, 2026 00:08 View session

Copilot AI reviewed Jun 10, 2026

View reviewed changes

dgarske force-pushed the supplicant branch 2 times, most recently from efe6635 to d71bf94 Compare June 17, 2026 18:25

dgarske requested a review from Copilot June 17, 2026 18:29

Copilot started reviewing on behalf of dgarske June 17, 2026 18:32 View session

Copilot AI reviewed Jun 17, 2026

View reviewed changes

Comment thread src/supplicant/eapol.c

Comment thread src/supplicant/test_eap_certs.h Outdated

Comment thread tools/hostapd/run_hostapd_test.sh

Comment thread src/port/rp2350_cyw43439/cyw43439_wifi.h

Comment thread src/port/rp2350_cyw43439/cyw43439_wifi.c Outdated

dgarske force-pushed the supplicant branch from d71bf94 to d90dd42 Compare June 17, 2026 21:09

dgarske added 4 commits June 18, 2026 15:20

wolfSupplicant: clean-room WPA/WPA2/WPA3 supplicant + interop harness

eed79b4

STM32H563: wired IEEE 802.1X EAP-TLS demo (wolfSupplicant on hardware)

907c888

Pico 2 W (RP2350 + CYW43439): bare-metal wolfIP port

9bc591b

dgarske force-pushed the supplicant branch from d90dd42 to 9bc591b Compare June 18, 2026 23:36

dgarske requested a review from Copilot June 18, 2026 23:38

Copilot started reviewing on behalf of dgarske June 18, 2026 23:38 View session

Copilot AI reviewed Jun 18, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

wolfSupplicant: clean-room WPA/WPA2/WPA3 supplicant (PSK 4-way, EAP-TLS, PEAP/MSCHAPv2, SAE with H2E)#123

wolfSupplicant: clean-room WPA/WPA2/WPA3 supplicant (PSK 4-way, EAP-TLS, PEAP/MSCHAPv2, SAE with H2E)#123
dgarske wants to merge 4 commits into
wolfSSL:masterfrom
dgarske:supplicant

dgarske commented May 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

dgarske commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

wolfSupplicant: clean-room WPA2 / WPA2-Enterprise / WPA3 supplicant

Commits

What's validated

Notable correctness work

Build flags

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dgarske commented May 20, 2026 •

edited

Loading